package com.gitee.wsl.text.dictomaton

/**
 * Perfect hash dictionary interface. A perfect hash dictionary provides
 * the functionality of a [Dictionary], plus:
 *
 *  * A hash code for each sequence in the dictionary ([.number]).
 *  * The character sequence of a given hash ([.sequence]).
 *
 */
interface PerfectHashDictionary : Dictionary {
    /**
     * Compute the perfect hash code of the given character sequence.
     *
     * @param seq The sequence to compute the perfect hash value for.
     * @return The perfect hash value of the sequence or <tt>-1</tt> if the sequence is
     * not in the automaton.
     */
    fun number(seq: CharSequence): Int

    /**
     * Compute the state for traversing the automaton given CharSequence seq. The
     * perfect hash code is available via [StateInfo.getHash]. The traversal
     * can be resumed using [.getStateInfo]
     *
     * @param seq The sequence to compute the perfect hash value for.
     * @return A StateInfo object containing the hash code and further information about the state
     * after the traversal for seq.
     */
    fun getStateInfo(seq: CharSequence): StateInfo?

    /**
     * Compute the state for traversing the automaton given CharSequence seq starting
     * at state startInfo. The perfect hash code is available via [StateInfo.getHash].
     *
     * @param seq The sequence to compute the perfect hash value for.
     * @param startInfo The state from which to resume traversal or null for the inital state.
     * @return  A StateInfo object containing the hash code and further information about the state
     * after the traversal for seq.
     */
    fun getStateInfo(seq: CharSequence, startInfo: StateInfo?): StateInfo?

    /**
     * Compute the sequence corresponding to the given hash code.
     *
     * @param hashCode The hash code.
     * @return The sequence corresponding to the hash code or <tt>null</tt> if there is
     * no sequence with that code in the automaton.
     */
    fun sequence(hashCode: Int): String?
}
